Docs Italia beta

Documenti pubblici, digitali.

Linee Guida sull'interoperabilità tecnica delle Pubbliche Amministrazioni Bozza in consultazione documentazione
Progetto: Progetto demo
Amministrazione: Organizzazione demo
Informazioni
Sorgente
Azioni

6.2.2. [NONBLOCK_PULL_SOAP] Not Blocking Pull SOAP

Nel caso in cui il profilo venga implementato con tecnologia SOAP, DEVONO essere rispettate le seguenti regole:

  • L’interfaccia di servizio dell’erogatore fornisce tre metodi differenti al fine di inoltrare una richiesta, controllare lo stato ed ottenerne il risultato;
  • La specifica dell’interfaccia dell’erogatore DEVE indicare l’header SOAP X-Correlation-ID;
  • Al passo (2), l’erogatore DEVE fornire insieme all’acknowledgement della richiesta nel body, un CorrelationID riportato nel header custom SOAP X-Correlation-ID;
  • Al passo (3), il fruitore DEVE utilizzare il CorrelationID ottenuto al passo (2) per richiedere lo stato di processamento di una specifica richiesta;
  • Al passo (4) l’erogatore, quando il processamento non si è ancora concluso fornisce informazioni circa lo stato della lavorazione della richiesta, quando invece il processamento si è concluso risponde indicando in maniera esplicita il completamento;
  • Al passo (5), il fruitore utilizza il CorrelationID di cui al passo (2) al fine di richiedere il risultato della richiesta;
  • Al passo (6), l’erogatore fornisce il risultato del processamento.

6.2.2.1. Regole di processamento

Nel caso di errore il WS-I Basic Profile Version 2.0 richiede l’utilizzo del meccanismo della SOAP fault per descrivere i dettagli dell’errore. Al ricevimento della richiesta da parte del fruitore, l’erogatore:

6.2.2.2. Esempio

Specifica Servizio Erogatore

https://api.ente.example/soap/nome-api/v1?wsdl

<?xml version='1.0' encoding='UTF-8'?>
<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:tns="http://ente.example/nome-api"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap12/" 
    name="SOAPPullService" 
    targetNamespace="http://ente.example/nome-api">
    <wsdl:types>
        <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
            xmlns:tns="http://ente.example/nome-api" attributeFormDefault="unqualified" elementFormDefault="unqualified" targetNamespace="http://ente.example/nome-api">

            <xs:element name="MProcessingStatus" type="tns:MProcessingStatus" />
            <xs:element name="MProcessingStatusResponse" type="tns:MProcessingStatusResponse" />

            <xs:element name="MRequest" type="tns:MRequest" />
            <xs:element name="MRequestResponse" type="tns:MRequestResponse" />

            <xs:element name="MResponse" type="tns:MResponse" />
            <xs:element name="MResponseResponse" type="tns:MResponseResponse" />

            <xs:element name="ErrorMessageFault" nillable="true" type="tns:errorMessageFault" />
            <xs:element name="X-Correlation-ID" nillable="true" type="xs:string" />

            <xs:complexType name="MProcessingStatus"/>
            <xs:complexType name="MProcessingStatusResponse">
                <xs:sequence>
                    <xs:element name="return" type="tns:processingStatus" />
                </xs:sequence>
            </xs:complexType>

            <xs:complexType name="MRequest">
                <xs:sequence>
                    <xs:element name="M" type="tns:mType" />
                </xs:sequence>
            </xs:complexType>
            <xs:complexType name="MRequestResponse">
                <xs:sequence>
                    <xs:element minOccurs="0" name="return" type="tns:processingStatus" />
                </xs:sequence>
            </xs:complexType>

            <xs:complexType name="MResponse"/>
            <xs:complexType name="MResponseResponse">
                <xs:sequence>
                    <xs:element minOccurs="0" name="return" type="tns:mResponseType" />
                </xs:sequence>
            </xs:complexType>

            <xs:complexType name="mType">
                <xs:sequence>
                    <xs:element minOccurs="0" name="o_id" type="xs:int" />
                    <xs:element minOccurs="0" name="a" type="tns:aComplexType" />
                    <xs:element minOccurs="0" name="b" type="xs:string" />
                </xs:sequence>
            </xs:complexType>
            <xs:complexType name="aComplexType">
                <xs:sequence>
                    <xs:element maxOccurs="unbounded" minOccurs="0" name="a1s" nillable="true" type="xs:string" />
                    <xs:element minOccurs="0" name="a2" type="xs:string" />
                </xs:sequence>
            </xs:complexType>

            <xs:complexType name="processingStatus">
                <xs:sequence>
                    <xs:element name="status" type="xs:string" />
                    <xs:element name="message" type="xs:string" />
                </xs:sequence>
            </xs:complexType>

            <xs:complexType name="mResponseType">
                <xs:sequence>
                    <xs:element minOccurs="0" name="c" type="xs:string" />
                </xs:sequence>
            </xs:complexType>

            <xs:complexType name="errorMessageFault">
                <xs:sequence>
                    <xs:element name="customFaultCode" type="xs:string" />
                </xs:sequence>
            </xs:complexType>
        </xs:schema>
    </wsdl:types>

    <wsdl:message name="MProcessingStatus">
        <wsdl:part element="tns:MProcessingStatus" name="parameters"/>
        <wsdl:part element="tns:X-Correlation-ID" name="X-Correlation-ID"/>
    </wsdl:message>

    <wsdl:message name="MProcessingStatusResponse">
        <wsdl:part element="tns:MProcessingStatusResponse" name="parameters"/>
    </wsdl:message>

    <wsdl:message name="MRequest">
        <wsdl:part element="tns:MRequest" name="parameters"/>
    </wsdl:message>

    <wsdl:message name="MRequestResponse">
        <wsdl:part element="tns:MRequestResponse" name="result"/>
        <wsdl:part element="tns:X-Correlation-ID" name="X-Correlation-ID"/>
    </wsdl:message>

    <wsdl:message name="MResponse">
        <wsdl:part element="tns:MResponse" name="parameters"/>
        <wsdl:part element="tns:X-Correlation-ID" name="X-Correlation-ID"/>
    </wsdl:message>

    <wsdl:message name="MResponseResponse">
        <wsdl:part element="tns:MResponseResponse" name="parameters"/>
    </wsdl:message>

    <wsdl:message name="ErrorMessageException">
        <wsdl:part element="tns:ErrorMessageFault" name="ErrorMessageException"/>
    </wsdl:message>

    <wsdl:portType name="SOAPPull">
        <wsdl:operation name="MRequest">
            <wsdl:input message="tns:MRequest" name="MRequest"/>
            <wsdl:output message="tns:MRequestResponse" name="MRequestResponse"/>
            <wsdl:fault message="tns:ErrorMessageException" name="ErrorMessageException"/>
        </wsdl:operation>

        <wsdl:operation name="MProcessingStatus">
            <wsdl:input message="tns:MProcessingStatus" name="MProcessingStatus"/>
            <wsdl:output message="tns:MProcessingStatusResponse" name="MProcessingStatusResponse"/>
            <wsdl:fault message="tns:ErrorMessageException" name="ErrorMessageException"/>
        </wsdl:operation>

        <wsdl:operation name="MResponse">
            <wsdl:input message="tns:MResponse" name="MResponse"/>
            <wsdl:output message="tns:MResponseResponse" name="MResponseResponse"/>
            <wsdl:fault message="tns:ErrorMessageException" name="ErrorMessageException"/>
        </wsdl:operation>
    </wsdl:portType>
    
    <wsdl:binding name="SOAPPullServiceSoapBinding" type="tns:SOAPPull">
        <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http" />

        <wsdl:operation name="MRequest">
            <soap:operation soapAction="" style="document" />

            <wsdl:input name="MRequest">
                <soap:body use="literal" />
            </wsdl:input>

            <wsdl:output name="MRequestResponse">
                <soap:header message="tns:MRequestResponse" part="X-Correlation-ID" use="literal"/>
                <soap:body parts="result" use="literal" />
            </wsdl:output>

            <wsdl:fault name="ErrorMessageException">
                <soap:fault name="ErrorMessageException" use="literal" />
            </wsdl:fault>

        </wsdl:operation>

        <wsdl:operation name="MProcessingStatus">
            <soap:operation soapAction="" style="document" />

            <wsdl:input name="MProcessingStatus">
                <soap:header message="tns:MProcessingStatus" part="X-Correlation-ID" use="literal"/>
                <soap:body parts="parameters" use="literal" />
            </wsdl:input>

            <wsdl:output name="MProcessingStatusResponse">
                <soap:body use="literal" />
            </wsdl:output>

            <wsdl:fault name="ErrorMessageException">
                <soap:fault name="ErrorMessageException" use="literal" />
            </wsdl:fault>

        </wsdl:operation>

        <wsdl:operation name="MResponse">
            <soap:operation soapAction="" style="document" />

            <wsdl:input name="MResponse">
                <soap:header message="tns:MResponse" part="X-Correlation-ID" use="literal"/>
                <soap:body parts="parameters" use="literal" />
            </wsdl:input>

            <wsdl:output name="MResponseResponse">
                <soap:body use="literal" />
            </wsdl:output>

            <wsdl:fault name="ErrorMessageException">
                <soap:fault name="ErrorMessageException" use="literal" />
            </wsdl:fault>
        </wsdl:operation>
    </wsdl:binding>

    <wsdl:service name="SOAPPullService">
        <wsdl:port binding="tns:SOAPPullServiceSoapBinding" name="SOAPPullPort">
            <soap:address location="https://api.ente.example/soap/nome-api/v1" />
        </wsdl:port>
    </wsdl:service>

</wsdl:definitions>

Di seguito un esempio di chiamata ad M in cui l’erogatore risponde di avere preso in carico la richiesta.

Endpoint

https://api.ente.example/soap/nome-api/v1

Method MRequest

  1. Request Body
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
    xmlns:m="http://ente.example/nome-api">
    <soap:Body>
        <m:MRequest>
            <M>
                <o_id>1234</o_id>
                <a>
                    <a1s>1</a1s>
                    <a2>prova</a2>
                </a>
                <b>prova</b>
            </M>
        </m:MRequest>
    </soap:Body>
</soap:Envelope>
  1. Response Body (HTTP status code 200 OK)
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
    xmlns:m="http://ente.example/nome-api">
    <soap:Header>
        <m:X-Correlation-ID>c8e191a8-f34f-41ed-82ea-68e096466707</m:X-Correlation-ID>
    </soap:Header>
    <soap:Body>
        <m:MRequestResponse>
            <return>
                <status>accepted</status>
                <message>Preso carico della richiesta</message>
            </return>
        </m:MRequestResponse>
    </soap:Body>
</soap:Envelope>

Di seguito un esempio di chiamata con cui il fruitore verifica l’esecuzione di M nei casi di processamento ancora in atto e di processamento avvenuto.

Endpoint

https://api.ente.example/soap/nome-api/v1

Method MProcessingStatus

  1. Request Body status
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
    xmlns:m="http://ente.example/nome-api">
    <soap:Header>
        <m:X-Correlation-ID>c8e191a8-f34f-41ed-82ea-68e096466707</m:X-Correlation-ID>
    </soap:Header>
    <soap:Body>
        <m:MProcessingStatus/>
    </soap:Body>
</soap:Envelope>
  1. Response Body (HTTP status code 200 OK) status in attesa
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
    xmlns:m="http://ente.example/nome-api">
    <soap:Body>
        <m:MProcessingStatusResponse>
            <return>
                <status>processing</status>
                <message>Richiesta in fase di processamento</message>
            </return>
        </m:MProcessingStatusResponse>
    </soap:Body>
</soap:Envelope>
  1. Response Body (HTTP status code 200 OK) status completata
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
    xmlns:m="http://ente.example/nome-api">
    <soap:Body>
        <m:MProcessingStatusResponse>
            <return>
                <status>done</status>
                <message>Richiesta completata</message>
            </return>
        </m:MProcessingStatusResponse>
    </soap:Body>
</soap:Envelope>

Di seguito un esempio di chiamata con cui il fruitore richiede l’esito della sua richiesta.

Endpoint

https://api.ente.example/soap/nome-api/v1

Method MResponse

  1. Request Body result
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
    xmlns:m="http://ente.example/nome-api">
    <soap:Header>
        <m:X-Correlation-ID>c8e191a8-f34f-41ed-82ea-68e096466707</m:X-Correlation-ID>
    </soap:Header>
    <soap:Body>
        <m:MResponse/>
    </soap:Body>
</soap:Envelope>
  1. Response Body (HTTP status code 200 OK) result
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
    xmlns:m="http://ente.example/nome-api">
    <soap:Body>
        <m:MResponseResponse>
            <return>
                <c>OK</c>
            </return>
        </m:MResponseResponse>
    </soap:Body>
</soap:Envelope>